﻿#region Header
// ------------------------ Licence / Copyright ------------------------
// 
// ScrumTable for Scrum Meeting Support
// Copyright © HSR - Hochschule für Technik Rapperswil
// All Rights Reserved
// 
// Author:
//  Michael Gfeller Silvan Gehrig Patrick Boos
// 
// ---------------------------------------------------------------------
#endregion

#region Usings

using System;
using System.Collections.Generic;
using ScrumTable.Common.Collections;

#endregion

namespace ScrumTable.DL.Data.Common
{
    /// <summary>
    /// The data access object encapsulates all service routines in order
    /// to access data from an external system.
    /// </summary>
    /// <remarks>The implementation of the data object class follows the Data Access Object pattern.</remarks>
    public interface IDataAccessObject : IDisposable
    {
        #region Properties
        //--------------------------------------------------------------------
        // Properties
        //--------------------------------------------------------------------

        #endregion

        #region Methods
        //--------------------------------------------------------------------
        // Methods
        //--------------------------------------------------------------------

        /// <summary>
        /// Creates a new IDataObject below the given parent id chain.
        /// </summary>
        /// <param name="parentIdChain">Global unique ids of the parent objects.</param>
        /// <returns>Returns the created object.</returns>
        IDataObject Insert(ValueChain<string> parentIdChain);

        /// <summary>
        /// Deletes the corresponding item from the data storage.
        /// </summary>
        /// <param name="parentIdChain">Global unique ids of the parent objects.</param>
        /// <param name="toDelete">Value which should be deleted.</param>
        /// <return>Returns true if the object has been deleted.</return>
        bool Delete(ValueChain<string> parentIdChain, IDataObject toDelete);

        /// <summary>
        /// Deletes all items from the data storage with the given parent id.
        /// </summary>
        /// <param name="parentIdChain">Global unique ids of the parent objects.</param>
        void Delete(ValueChain<string> parentIdChain);

        /// <summary>
        /// Deletes all items from the data storage.
        /// </summary>
        void Clear();

        /// <summary>
        /// Updates the corresponding item in the data storage.
        /// </summary>
        /// <param name="parentIdChain">Global unique ids of the parent objects.</param>
        /// <param name="toUpdate">Value which should be updated.</param>
        void Update(ValueChain<string> parentIdChain, IDataObject toUpdate);

        /// <summary>
        /// Moves a IDataObject using the given id into a new parent object.
        /// </summary>
        /// <param name="parentIdChain">Global unique ids of the parent objects.</param>
        /// <param name="toMove">Specifies the data object to move inside the data storage.</param>
        /// <param name="newParentIdChain">Specifies the new parent id chain.</param>
        void Update(ValueChain<string> parentIdChain, IDataObject toMove, ValueChain<string> newParentIdChain);

        /// <summary>
        /// Retrieves all data objects which are stored in conjunction
        /// with the specified arguments.
        /// </summary>
        /// <param name="parentIdChain">Global unique ids of the parent objects.</param>
        /// <returns>Returns the retrieved data objects.</returns>
        ICollection<IDataObject> GetAll(ValueChain<string> parentIdChain);

        /// <summary>
        /// Retrieves all data objects which are stored in conjunction
        /// with the specified arguments.
        /// The data is retuned as callback and will be evaluated asynchronously but the callback will be fired in the main message loop.
        /// </summary>
        /// <param name="parentIdChain">Global unique ids of the parent objects.</param>
        /// <param name="callback">Specifies the asynchronous callback method. The callback value is of type DataResult&gt;ICollection&gt;IDataObject&lt;&lt;.</param>
        void GetAll(ValueChain<string> parentIdChain, AsyncCallback callback);

        /// <summary>
        /// Retrieves all data objects which are stored in the current dao.
        /// The structure of the given data objects is defined as follows:
        /// <example>
        /// <code>
        ///  [Parent Id Chain 1] -> Child Instance 1
        ///                      -> Child Instance 2
        ///                      -> Child Instance n
        /// 
        ///  [Parent Id Chain 2] -> Child Instance 3
        ///                      -> Child Instance 4
        ///                      -> Child Instance x
        /// </code>
        /// </example>
        /// </summary>
        /// <returns>Returns the retrieved data objects.</returns>
        IEnumerable<KeyValuePair<ValueChain<string>, ICollection<IDataObject>>> GetAll();

        /// <summary>
        /// Gets a single data object by its unqiue id.
        /// </summary>
        /// <param name="parentIdChain">Global unique ids of the parent objects.</param>
        /// <param name="id">Id of the data object.</param>
        /// <returns>Returns the retieved element or a null pointer, if it could not be found.</returns>
        IDataObject GetById(ValueChain<string> parentIdChain, string id);

        /// <summary>
        /// Gets a single data object by its unqiue id.
        /// The data is retuned as callback and will be evaluated asynchronously but the callback will be fired in the main message loop.
        /// </summary>
        /// <param name="parentIdChain">Global unique ids of the parent objects.</param>
        /// <param name="id">Id of the data object.</param>
        /// <param name="callback">Specifies the asynchronous callback method. The callback value is of type DataResult&gt;IDataObject&lt;.</param>
        void GetById(ValueChain<string> parentIdChain, string id, AsyncCallback callback);

        #endregion

        #region Events
        //--------------------------------------------------------------------
        // Events
        //--------------------------------------------------------------------

        /// <summary>
        /// Occurs when the content of the data access object changes.
        /// </summary>
        event DataAccessObjectChangedEventHandler DataAccessObjectChanged;

        #endregion
    }
}